package com.seventhdawn.gwt.rcx.client;

import com.google.gwt.user.client.rpc.IsSerializable;
import com.seventhdawn.gwt.rcx.client.annotation.ClientProxySuperclass;

/**
 * This class handles RPC context management on the client.
 * <p>
 * RPC context is an extra piece of information sent along with each RPC
 * request. RPC context can be therefore viewed as the <em>conversational
 * state</em> during client-server RPC communications, making the whole
 * communication process stateful. RPC context is managed and stored on the
 * client side only, and as such essentially represents a <em>client-side
 * session</em>.
 * <p>
 * The main philosophy of such mechanism is to allow servers to remain truly
 * stateless during RPC communications, promoting application scalability and
 * overall performance in consequence.
 * <p>
 * To utilize RPC context support, use {@link RPCContextServiceProxy} as the
 * proxy superclass for your client-side
 * {@link com.google.gwt.user.client.rpc.RemoteService RemoteService} interface
 * implementations via the {@link ClientProxySuperclass} annotation.
 * 
 * @see ClientProxySuperclass
 * @see RPCContextServiceProxy
 * @author vojtech.szocs
 */
public final class RPCClientContext {

    // RPC context object as a singleton on the client
    private static IsSerializable ctxObj = null;

    // no need to instantiate this class
    private RPCClientContext() {
    }

    /**
     * Returns the RPC context object to be serialized and transferred along
     * with each RPC request.
     * 
     * @return RPC context object managed by the client.
     */
    public static IsSerializable get() {
        return ctxObj;
    }

    /**
     * Sets the RPC context object to be serialized and transferred along with
     * each RPC request.
     * <p>
     * Since the client manages a single instance of the context object, it is
     * recommended to call this method early on within your application entry
     * point(s).
     * 
     * @param ctxObj RPC context object to set.
     */
    public static void set(IsSerializable contextObject) {
        ctxObj = contextObject;
    }

}
